# Kernel development

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

# Objectives and Scope

This section guides you through **recompiling the kernel and DTB, and replacing them in the Debian system** after implementing customization requirements (drivers/configurations/patches, etc.).

- **Applicable Platform**: Quectel Pi-H1 (based on Pi-H1 Linux SDK)

- **Applicable System**: Debian

# Prerequisites

## Development Environment Requirements (Recommended)

- Available Linux host environment (Ubuntu/Debian-based systems are acceptable, subject to SDK requirements)

- Sufficient disk space (source code + out directory + build artifacts)

- Shell environment capable of executing SDK scripts (typically bash)

## Obtaining/Preparing the SDK

Ensure you have obtained the **Pi-H1 Linux SDK** and are using an SDK version that matches the current Debian image (or the same release/tag). If the SDK version does not match the image version, the following issues may occur:

- Kernel version/module version mismatch causing driver loading failures

- DTB device tree mismatch causing peripherals to be unavailable or preventing boot

# Build Command Workflow (On-Demand Individual Build of Kernel/DTB)

This section focuses on: after completing environment initialization and project configuration, **building the kernel and DTB individually on-demand** through SDK-provided target commands, for kernel/DTB replacement in the Debian system.

## Navigate to SDK Directory

```bash
cd your/path/to/Pi-H1-Linux-SDK/
```

## Build Environment: Initialize Build Environment

```bash
source quectel_build/compile/build.sh
```

Notes:

- This script loads SDK build functions (such as `buildconfig/buildkernel/builddtb/buildpackage`, etc.) and sets necessary environment variables.

- If not `source` d, subsequent commands will typically prompt "command not found" or indicate missing environment.

- After executing this command, the terminal will automatically switch to the `build-qcom-wayland` directory, which is normal. Subsequent `buildconfig`, `buildall`, and `buildpackage` commands will be executed in this directory.

## Select Build Configuration (Step One)

```bash
buildconfig QSM565DWF QSM565DWFPIARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X STD
```

Notes:

- **QSM565DWF**: Target platform/product family configuration (selecting the correct platform is crucial, as it affects kernel configuration, device tree, packaging rules, etc.).

- **QSM565DWFPIARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X**: Project version/configuration (example). Please select from the valid fields prompted in practice.

- **STD**: Standard build configuration (different configurations may affect build options, debug symbols, packaging content, etc.).

You can input user-customized `project_name`, `project_rev`, and `custom_name` based on prompts, selecting currently valid fields from the prompted `Valid Projects` and `Valid CUST_NAME` for user customization.

After successful configuration, you will see the current build configuration information (example):

```plaintext
MACHINE    = qcm6490-idp
DISTRO     = qcom-wayland
BUILDTYPE  = default
BSP-TYPE   = qcom-custom-bsp
```

And the confirmed project configuration (example):

```plaintext
Current QUECTEL_PROJECT_NAME = QSM565DWF
Current QUECTEL_PROJECT_REV  = QSM565DWFPIARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X
Current QUECTEL_CUSTOM_NAME  = STD
```

## Enable Kernel Build Switch

```bash
setopenkernel
```

Notes:

- This step is used to **enable kernel-related build processes** in the SDK build system (including kernel/dtb and possibly modules packaging).

- If this step is not executed, subsequent `buildkernel/builddtb/buildpackage` may not produce the expected kernel/DTB files, or may follow the default "closed-source/pre-built artifacts" branch (subject to SDK rules).

## Individual Kernel Build: buildkernel (Generate efi.bin)

```bash
buildkernel
```

Notes:

- This command triggers kernel build in the SDK environment and generates the boot-required kernel artifact **`efi.bin`**.

- **Artifact Output Directory**: After build completion, `efi.bin` will appear at:  
    - `Pi-H1-Linux-SDK/quectel_build/output/efi.bin`

- **Firmware Package Replacement Principle**: The `efi.bin` under `output/` needs to be **copied and overwritten** to the firmware package directory generated by `buildpackage`, as the kernel file for final delivery/flashing (see "Step 7" below).

## Individual DTB Build: builddtb (Generate dtb.bin)

```bash
builddtb
```

Notes:

- This command generates the device tree artifact **`dtb.bin`** (which may contain multiple dtb packages/collections).

- **Artifact Output Directory**: After build completion, `dtb.bin` will appear at:  
    - `Pi-H1-Linux-SDK/quectel_build/output/dtb.bin`

- **Firmware Package Replacement Principle**: The `dtb.bin` under `output/` needs to be **copied and overwritten** to the firmware package directory generated by `buildpackage`, as the DTB file for final delivery/flashing (see "Step 7" below).

## Generate Firmware Package Directory and Replace Kernel/DTB: buildpackage + Overwrite Files

Execute `buildpackage` to generate the firmware package directory (`TARGET_DIR`), then overwrite the corresponding files in the firmware package directory with the new artifacts from **`quectel_build/output/`**.

```bash
buildpackage
```

Notes:

- This step typically takes **10~20 seconds**; after success, it will generate a firmware package directory (example):  
    - `Pi-H1-Linux-SDK/quectel_build/SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X/`

- **Key Point**: The directory generated by `buildpackage` is where the final flashing package/delivery package is located. After customizing the kernel/DTB, you need to overwrite and replace with the following files:  
    - Source: `Pi-H1-Linux-SDK/quectel_build/output/efi.bin`  
    - Source: `Pi-H1-Linux-SDK/quectel_build/output/dtb.bin`  
    - Target: The corresponding `efi.bin` and `dtb.bin` in the `Pi-H1-Linux-SDK/quectel_build/SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X/` directory

Example (illustrative, actual filenames subject to firmware package directory contents):

```bash
# Navigate to SDK root directorycd Pi-H1-Linux-SDK

# Overwrite files in firmware package with individually built artifactscp -f quectel_build/output/efi.bin quectel_build/SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X/efi.bin
cp -f quectel_build/output/dtb.bin quectel_build/SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X/dtb.bin
```

# Artifact Description (What Will Be Used for Debian Replacement)

This subsection helps customers quickly identify "which file exactly needs to be replaced":

- **efi.bin**: Kernel image package used for boot chain loading (on the Debian side, typically referenced in the boot partition/`/boot` or EFI-related directories).

- **dtb.bin**: Device tree-related artifact (may be a collection package). On the Debian side, it will eventually be loaded by the boot chain (path and configuration depend on the image's boot scheme).

- **package**: SDK aggregated artifact. It is recommended to use the package as the deliverable, which typically contains `efi.bin/dtb.bin` and necessary auxiliary files (actual structure subject to package contents).

# Verification and Rollback

## Verification

It is recommended to perform at least two types of verification:

- **Kernel Version Verification**: Confirm that the newly compiled kernel is running

- **Feature Point Verification**: Perform minimal closed-loop testing for your customized drivers/configuration items (e.g., peripheral enumeration, driver loading, dmesg keywords, etc.)

## Rollback

Recommended rollback strategy:

- Always keep a bootable old kernel/old DTB (file-level backup or dual boot entries)

- If the boot chain supports multiple boot entries (e.g., extlinux/grub), prioritize verifying the new kernel by "adding a new boot entry", and only overwrite the old file after confirming stability

# Common Issues

- **Build command prompts not found**: Have you executed `source quectel_build/compile/build.sh`?

- **buildkernel/builddtb produces no artifacts**: Have you selected the correct configuration with `buildconfig` and executed `setopenkernel`?

- **Cannot boot after replacement**: Prioritize rolling back to backup files; check if the kernel/DTB path referenced by boot entries matches the actual path

- **DTB not taking effect**: Confirm which dtb (or dtb.bin) is referenced in the boot configuration and verify that you are replacing the same target

- **Module version mismatch**: Confirm that `/lib/modules/`<kernel_version>`/` matches `uname -r` and execute `depmod -a`